t
Adding a Scrolling List to a Window

*22*Folks Database no longer loses track of Person objects created. However, it is a bit inconvenient to inspect the contents of the People persistent list.

To know which Person objects exist, and to have a means of accessing them, you enhance the Folks Database window with a scrolling list. This list should show the names of all the Person objects maintained in the People persistent.

This enhancement of your application requires a two-stage approach. A scrolling list is first added to the application window. Then the Add method is elaborated to update the scrolling-list entries each time a new Person object is added to the People persistent list.

To begin, do the following:

u If you are not running Folks Database, select Run Initial from the Exec menu to start your application running.

u With the Folks Database window displayed, select*35* *320*Enter Editor *573* from the Apple menu.

u Just to the right of the Name field, Command-drag a marquee about two inches wide and three inches tall.

u Double-click the new window item to open the Window Item *1170*editor. Scroll to the Scroll List entry, click to select it, and click the OK button. The Window Item dialog is replaced by the*303* Scroll List editor*967*.

u Type Name List in the List Name field.

___________________________________________________________
NOTE: Among the attributes of a Scroll List *1053*object is the value list attribute. This list attribute contains a collection of string items to be displayed in the scrolling list.*969*

The Scroll List editor List of Values field lets you specify the value list attribute when you create a Scroll List object in the*312* Window editor of the Application Builder. This can be handy if the list is going to have an unchanging set of values or if you want to specify some initial values that you plan to change during runtime.

In the Folks Database application, the scroll list’s value list attribute is updated dynamically during runtime to show all the names of Person objects stored in the People persistent at any point in time. Because the contents of the value list are handled programmatically, leave the List of Values field empty in the Scroll List editor*968*.
-----------------------------------------------------------

This completes the first phase of adding the scrolling-list function to Folks Database. The Scroll List item just sits there in your window now. To make it work, you modify the Add method.

u Click the OK button to dismiss the*304* Scroll List editor.

u Select*36* Exit Editor *361**574*and then Switch Context from the Apple menu to exit the Window editor and resume running your application.

u Click on the Name field, then type Bart, and click the Add button to pop up the Add execution window. Double-click the execution window to open the case window.

u Command-click the bottom edge of the lower People persistent operation to add a root. 

u Below and to the right of the People persistent, Option-Command--click a new operation connected to the Persistent root.

u Select Local from the Opers menu.

u Type Update the Name List and press Return.

This gives the Update the Name List local half the information it needs to do its task. The local can extract the name attribute of each item in the People persistent list. To update the scroll list, however, this local is going to need access to the window that has the scroll list to be updated.

u To the left of its existing terminal, Command-click on the top edge of the Update the Name List local operation. This creates a new terminal, which becomes the selected item.

u The Folks Database window object comes into the Add method on the left root of the input bar. So, Option-point-click a datalink from the new Update the Name List local terminal all the way up to the left root of the input bar of Add.

Once the datalink is connected to the input-bar root, the datalink is visibly routed behind any operation icons between its root and terminal connectors.

A datalink always connects only roots and terminals. Whenever you see a datalink *255*intersecting an operation icon where there is no root or terminal, the datalink is not passing data to that operation. The datalink is passing behind the icon.

In creating more complex Prograph methods, you inevitably have datalinks routing behind operations and *254*crisscrossing other datalinks. Datalinks are always straight lines, so crisscrosses are not confusing. Grabbing and moving icons, expanding the case-window size, and scrolling all help you*1090* minimize dataflow*900* layout complexities.

The more you understand about Prograph, the easier it becomes to layout well-organized methods. Local methods*529* are especially helpful for reducing the visual complexity of your methods and for providing logical organization.

u Command-click the right terminal of the Update the Name List *207*local operation and type People as a terminal comment. Command-click the left terminal of the local and type Window as a comment. These comments*172* will be copied to the input-bar roots of the Local operation, as reminders of what data and objects the Local method processes.

u Select the Update the Name List operation and choose*177* Propagate Comments*444* *643*from the Info menu. .

u Double-click the Update the Name List operation to open its case window. Notice that the comments were propagated to the roots of the input bar. You can Command-drag these comments to different locations if they get in the way of datalinks and operations you add as you continue.

u Select the right root of the input bar. Option-Command-click a new operation. Turn it into a name get operation.

u Click the terminal of the name get operation. Shift-click the right root of the name get operation. The root and terminal are both selected.

_____________________________________
NOTE: Now for something new and exciting!
-------------------------------------

u Select*523* List *584*from the Controls menu. The name get operation turns into a *518*multiplex,*745* which looks like a stack of operations, one behind the other, implying multiple executions. The selected terminal and root turn from simple circles into *514*list*197* *747*annotations, (…).

___________________________________________________________
NOTE: Multiplexes and root- and terminal-control annotations are one of the most exciting and powerful features of the Prograph dataflow language. Part 2, “Tutorials,” in this manual covers these features in much greater detail. The important thing to understand here is that multiplexes are operations that execute multiple times before they output. The multiple executions of a multiplex are generally for one of two purposes. An operation can feed its output to its inputs for a number of *503*iterations. This is called a loop multiplex. Or an operation can execute a number of times to perform its action on each member of a list, which is called a list multiplex. Further, you can mix list*515* and loop control annotations*198* on the roots and terminals of an operation to create all kinds of powerful operations that are expressed in a single icon in your method.

A list annotation on an input terminal indicates that the operation is to perform its action on each member of the incoming list. A list annotation on a root means to collect the results of the multiplex in a list and pass the entire list on after all executions of the multiplex have been performed. For example, the +1 primitive operation takes an input, adds one to it, and outputs the result. If you annotate its terminal and root with list controls and feed it a list, the operation adds one to each member of the list and then passes on the resulting list:

The list-annotated name get operation in the Update the Name List local method takes the list of Person objects and gets the name attribute of each Person instance. It then outputs the list of their names. So, a list of objects comes in and a list of strings goes out. The list of strings representing the Person objects names is what you want to display in the Scroll List item in the Folks Database window.
-----------------------------------------------------------

u Select the left root of the input bar. Option-Command-click a new operation. Turn it into a*376* find-item primitive operation.

u Create a constant, Name List, connected to the right terminal input of find-item. This gets the Scroll List item from the item list attribute of the incoming window object. The Scroll List object passes out of the find-item *843*operation on the right root.

u Select the right root of find-item and Option-command-click an operation below and to the right of find-item. Turn this new operation into a value list set operation. The Scroll List passes into the left terminal of the value list set operation. 

u To display the list of names of all the Person objects in the Scroll List, create a datalink between the list annotated root of the multiplex name get operation and the right terminal of the value list set operation.

u Close the Update the Name List local-method case window.

u Close the Add case window to get back to the Add execution window.

u Press Return a few times to step through the Add method. When the execution highlight gets to the Update the Name List local, pressing Return results in the Scroll List displaying all the names of Person objects in the People persistent list. (Your list of names may vary.)

u To turn the pop-up execution windows off temporarily, select*259* Debug *333**614*from the Exec menu. The check mark, indicating debug mode is on, disappears from the Debug item, indicating debug mode is off. You can now run Folks Database without having to step through methods.

u Add a few more people to see how well your application is shaping up. When enough names fill the scroll list, the scroll bar activates.

u Select Debug from the Exec menu.  This reactivates debugging mode.

u Select Quit from the File menu to return to the Prograph Editor. Select Save Folks Database from the File menu.

Congratulations. You have reached a significant plateau in familiarizing yourself with the Prograph language and Application Builder. You may want to stop here and continue on to chapter 4, “Conceptual Foundations.” Or you may want to try the following challenges.